<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta http-equiv="content-style-type" content="text/css">
<link rel="stylesheet" type="text/css" href="style.css">
<title>DexGuard Quick Start</title>
</head>
<body>

<script type="text/javascript" language="JavaScript">
<!--
if (window.self==window.top)
  document.write('<a target="_top" href="index.html#quickstart.html" class="largebutton">DexGuard index</a>')
//-->
</script>
<noscript>
<a target="_top" href="index.html#quickstart.html" class="largebutton">DexGuard index</a>
</noscript>

<h2>Quick Start</h2>

<b>DexGuard</b> is a specialized optimizer and obfuscator for Android
applications. It is easy to integrate in your Android build process. Once
installed, it works transparently, producing code that is optimized and more
difficult to crack.

<h3>Setting Up the Ant Build</h3>

If you develop your applications with the Ant build process of the Android
SDK Tools (revision 21.0.0 or higher), you can enable DexGuard as follows:
<ol>
<li>Copy the two configuration files from DexGuard's <code>ant</code>
    directory to the main directory of your Android project:
<pre>
dexguard-project.txt
custom_rules.xml
</pre></li>
<li>Specify the main DexGuard directory on your system in the configuration
    file <code>local.properties</code> in your Android project. For instance:
<pre>
dexguard.dir=/usr/local/DexGuard5.0
</pre></li>
</ol>

The standard Ant build process will now automatically use DexGuard for your
Android project.

<h3>Setting Up the Eclipse Plugin</h3>

If you develop your applications in Eclipse (version 3.7 or higher) with the
plugin of the Android Developer Tools (version 23.0.1.1256982 or higher),
you can enable DexGuard as follows:
<ol>
<li>Optionally copy the configuration file from DexGuard's <code>ant</code>
    directory to the main directory of your Android project:
<pre>
dexguard-project.txt
</pre></li>
<li>Copy the plugin from DexGuard's <code>eclipse</code> directory to
    the <code>dropins</code> directory of your Eclipse install:
<pre>
com.saikoa.dexguard.eclipse.adt_*.jar
</pre></li>
</ol>

You're set! The standard Eclipse build process will automatically use DexGuard
for all Android builds.

<h3>Getting the Most Out of DexGuard</h3>

DexGuard has been configured to work out of the box for most projects. It
transparently combines the functionality of ProGuard, <code>dx</code>,
<code>apkbuilder</code>, <code>signjar</code>, and <code>zipalign</code> in a
single, seamless process. Instead of creating a whole series of intermediary
and final <code>.apk</code> files in the <code>bin</code> directory, it just
produces the final <code>.apk</code> file.
<p>

When building in debug mode, DexGuard only converts and packages your code.
When building in release mode, it additionally optimizes and obfuscates the
code.
<p>

Once your basic setup works, you should have a look at DexGuard's specialized
optimizations and advanced obfuscation. For optimally protecting your
application, consider the following options:
<ul class="spacious">
<li><a href="usage.html#encryptstrings"><b>-encryptstrings</b></a>:
    Encrypt sensitive strings in your code.</li>
<li><a href="usage.html#encryptclasses"><b>-encryptclasses</b></a>:
    Encrypt entire classes.</li>
<li><a href="usage.html#encryptassetfiles"><b>-encryptassetfiles</b></a>:
    Encrypt streamed asset files.</li>
<li><a href="usage.html#encryptnativelibraries"><b>-encryptnativelibraries</b></a>:
    Encrypt native libraries.</li>
<li><a href="usage.html#accessthroughreflection"><b>-accessthroughreflection</b></a>:
    Hide access to sensitive APIs through reflection.</li>
<li><b>samples/TamperDetection</b>: Add tamper detection to your
    application.</li>
<li><b>samples/EnvironmentCheck</b>: Check the environment in which your
    application is running.</li>
<li><b>samples/LoggingRemoval</b>: Thoroughly remove Android logging
    code.</li>
</ul>
You can specify custom configurations in the following optional
files:
<pre>
dexguard-project.txt         (for all targets)
dexguard-project-debug.txt   (for target 'debug')
dexguard-project-release.txt (for target 'release')
proguard-project.txt         (for backward compatibility with ProGuard)
</pre>
All options are all illustrated in the sample projects in the directory
<code>samples</code>. Our <a href="bestpractices.html">best practices</a> can
serve as a guideline.

<h3>Quick Troubleshooting</h3>

If you have problems setting up your project:
<ul class="spacious">
<li>Make sure you are using a recent Android SDK. You can update it
    interactively with the standard command:
<pre>
android
</pre></li>
<li>If you can't find <code>local.properties</code>, make sure your project is
    updated to work with the installed Android SDK. For example:
<pre>
android update project --path MyAndroidProjectDirectory
</pre></li>
<li>You can build and run a sample to quickly check if your environment is set
    up properly:
<pre>
cd samples/HelloWorld
  <i>(edit sdk.dir in the file local.properties)</i>
ant debug install
</pre>
By default, the samples target "android-15", so you should have the target API
for Android 4.0.3 installed.
</ul>
<p>
If the obfuscated application doesn't work, you may have to add some custom
configuration to <code>dexguard-project.txt</code>. The most common issues on
the Android platform:
<ul class="spacious">
<li><b>ClassNotFoundException</b>: the application tries to access a class by
    means of reflection, but DexGuard has removed or obfuscated it. You should
    explicitly preserve the class. For example:
<pre>
-keep class mypackage.MyClass
</pre></li>
<li><b>NoSuchMethodException</b>: the application tries to access a method by
    means of reflection (for a WebView, for instance), but DexGuard has
    removed or obfuscated it. You should explicitly preserve the method. For
    example:
<pre>
-keepclassmembers class mypackage.MyClass {
    void myMethod(java.lang.String);
}
</pre></li>
</ul>

You can look at the generated files <code>bin/proguard/seeds.txt</code> and
<code>bin/proguard/usage.txt</code> to check which classes and class members
DexGuard has explicitly kept (due to the configuration), or removed (because
they appeared unused).
<p>
Please consult the
extensive <a href="troubleshooting.html">troubleshooting</a> section if you
encounter other issues.

<hr />
<address>
Copyright &copy; 2002-2014
<a target="other" href="http://www.saikoa.com/">Saikoa BVBA</a>.
</address>
</body>
</html>
